StringRelease Routine
 ----------------------------------------------------------------------------


 Action

 Deallocates variable-length strings that have been transferred to BASIC's
 string space from a non-BASIC routine.


 Syntax



  StringRelease( string-descriptor%);

 Remarks


 The syntax above is for the C language. For MASM, Pascal, and FORTRAN
 examples, see Chapter 13, "Mixed-Language Programming with Far Strings" in
 the  Programmer's Guide.

  StringRelease is used in mixed-language programming.  StringRelease is used
 by a non-BASIC routine to deallocate variable-length strings that have been
 transferred to BASIC's string space from the non-BASIC routine.

 Calls to the  StringRelease routine are made from a non-BASIC routine to
 free up space in BASIC's data area. The argument  string-descriptor% is an
 integer that is the near address of a string descriptor within a non-BASIC
 routine.

 BASIC automatically deallocates strings allocated by BASIC. However, strings
 that have been transferred to BASIC from a non-BASIC routine should be
 deallocated from the non-BASIC routine using the  StringRelease routine.
 (The reason for this is that  StringAssign transfers strings but not string
 descriptors. Without the string descriptor, BASIC cannot deallocate the
 string; the deallocation has to be done from the non-BASIC routine with
 StringRelease.)

 As an example, assume that you have passed a string from a MASM routine to
 BASIC's string space using  StringAssign. To deallocate this string,
 assuming a descriptor for the variable-length string exists at offset
 descriptor, the code would be as follows.

 leaax, descriptor ; offset of descriptor


 pushax


 extrnstringrelease. proc far


 call stringrelease


 Warning


 Use the  StringRelease routine only to deallocate variable-length strings
 that have been transferred to BASIC's string space from a non-BASIC routine.
 Never use it on strings created by BASIC. Doing so may cause unpredictable
 results.

 For more information on mixed-language programming with strings, see Chapter
 12, "Mixed-Language Programming" and Chapter 13, "Mixed-Language Programming
 with Far Strings" in the  Programmer's  Guide.


 See Also

  StringAddress,  StringAssign,  StringLength


 Example

 See the  StringAssign routine programming example, which uses the
 StringRelease routine.